





















                                          THE


                                        "FAST"


                                       COMPILER







                           (c) PETER CAMPBELL SOFTWARE 1992
















   FAST v3.000





                                       CONTENTS

                ───────────────────────────────────────────────────


                Introduction

                The Compiler

                FAST Commands
                Command Summary

                FAST Functions
                Function Summary

                FAST Expressions

                Compiler Directives
                Directive Summary

                Include Files

                Error Messages

                Example Program Documentation

INTRODUCTION


FAST!


FAST is a computer language designed specifically for the IBM PC and compatible 
computers. All FAST commands are optimised for speed and compactness, thus resulting in 
the fastest and smallest code possible compared to any other PC language.

FAST produces very short and efficient compiled programs for just about anything. 
Programs developed include a multi-file text editor, terminal emulator, find program, 
free flow database, dos command line editor and a 4GL database development system.

FAST is a procedural language, losely based on Basic, Pascal, C and Assembler.

Your version of FAST should include a compiler, include files and example programs.


Before reading this manual you may want to experiment with FAST and the example 
programs provided.

There are over 11,000 lines of example programs in over 20 programs.

After copying the FAST system to a directory on your hard disk run the batch program:
compile. Compile will compile all of the example programs automatically for you.

Run the demo program by typing: demo

Demo contains some fast screen displays using scrolling screens, windows and fast 
printing. After running the demo program you could edit/view the program by running the 
multi-file text editor, type: wt demo

While using wt, press F1 for help.

Some of the other example programs include: edit, pu, mis, game, shoot and ffind.

Try running all of the example programs, this will give you a feel for what FAST can 
do. View the example programs with wt or your favourite editor.

Two other programs have been written in FAST which may be of interest to many people, 
these programs have become seperate products and are available from Peter Campbell 
Software.

Free Flow Database (FFD) is a database of free format text. Text can be entered using 
the built in text editor or by importing text files. Users can search for text entries 
by entering in words to search for. Multiple searches can be done to restrict the text 
entries retrieved.

FASTBASE is a 4th Generation Database Application Development System. FASTBASE consists 
of a compiler, screen designer, database processor and utilities. FASTBASE is a very 
powerful database design tool, compared to dBASE, Paradox, Dataflex and all the others 
it is more compact, faster, much easier to use. The data dictionary and procedure 
language is very english like and powerful, making applications compact, easy to 
maintain, bug free and very user friendly. Ask for a demo!
THE COMPILER

The FAST compiler is called FAST.COM

To compile any program simply type: fast program

Typing FAST with no program name will display the help screen:

┌────────────────────────────────────────────────────────────────────────────────┐
│ FAST v3.000 (c) Peter Campbell, 14 Apr 92. -h for help.                        │
│                                                                                │
│ (c) Peter Campbell Software 1987-1992. Po Box 54-180, Mana, New Zealand.       │
│                                                                                │
│ HELP                                                                           │
│ ====                                                                           │
│                                                                                │
│ FAST [-h?mls] filename [>outfile]                                              │
│                                                                                │
│ h or ?   help                                                                  │
│ m        Maintenance - change default settings                                 │
│ l        Source listing                                                        │
│ s        Symbol table and memory usage                                         │
│ filename Program to be compiled (.F extension added)                           │
│ >outfile DOS redirection of output: for source or symbol table                 │
│                                                                                │
│ Example: "FAST -s wt" would compile wt.f and output a symbol table and         │
│          memory listing to screen.                                             │
│                                                                                │
│ Note: Options can be prefixed with a hyphen (-) or forward slash (/) and       │
│       can be before or after the filename.                                     │
└────────────────────────────────────────────────────────────────────────────────┘

Maintenance: FAST -m

A list of all FAST configuration options will appear, prompting you to enter new values 
for each option.

    ┌──────────────────────────────────┐
    │ Source File Buffer Size  [10240] │  Larger size may speed up compiler.
    │ Maximum Number of Labels [ 1500] │  Increase for HUGE programs.
    │ Label Memory             [30000] │  Increase for HUGE programs.
    │ Undefined Items Memory   [25000] │  Increase for HUGE programs.
    │                                  │
    │ Create Log File?         [N]     │  A file FAST.LOG can record all compilations.
    └──────────────────────────────────┘

The configuration file is called FAST.CFG, it must exist in the current directory, if 
none exists then it is created.
Source listing: FAST -l program

FAST will output every program line with the line number, code address and source. If 
any errors are detected then they will be printed, the compiler will not stop after the 
usual 5 error limit.

The listing can be redirected to a file using DOS redirection, eg: FAST -l wt >wt.lst

Symbol table and memory usage: FAST -s program

FAST will print an alphabetically sorted symbol table after a sucessful compilation. 
The symbol table lists all labels, variables, procedures, functions and other user 
defined words with the name, type and value.

A memory usage will also print, this details how much memory FAST required to compile 
and how much memory was left. If the memory left is getting low then increase the 
memory sizes by using FAST maintenance.

The memory usage also displays the compiled program memory requirements, ie: code size, 
stack size, window space (if windows are used) and variable/data space.

FAST COMMANDS

COLOUR

bright n
Sets the intensity bit of the current colour. Any printing will appear normal (n=0) or 
intense (n=1).

colour n
Sets the current colour used by cls, line, plot, print & scroll commands and functions.
colour is a command but can also be used as a variable or function to get the current 
colour.

The colour is an 8 bit number (0 to 255), the number is made up in binary as follows:
    fpppbiii
f=flash ppp=paper (background) b=bright (intensity) iii=ink (foreground)

A simple way of finding out the number for any colour combination is to use the program 
called 'colour'. See instructions on using colour in the Example Program section.

flash n
Sets the flash bit of the current colour. Any printing will appear still (n=0) or 
flashing (n=1).

ink n
Sets the current foreground colour. Any printing will appear with the foreground colour 
as specified.
0=black 1=blue 2=green 3=cyan 4=red 5=magenta 6=yellow 7=white

palette n
Determines which colour palette will be used for colour graphics screens.
Experiment with different numbers or consult a technical manual for which colours will 
be displayed, depending on the palette number.

paper n
Sets the current background colour. Any printing will appear with the background colour 
as specified.
0=black 1=blue 2=green 3=cyan 4=red 5=magenta 6=yellow 7=white

CONTROL

break
Executes the current on-break statement, same as pressing Ctrl-C or Ctrl-ScrollLock.

disable break
Turns the break key off, therefore the break key or break command will have no action.

enable break
Turns the break key on, the break key or break command will execute the current 
on-break statement.

endfor
Drops out of the current forever loop, resuming at the first line after the forever 
statement.

for var=n1 to n2 [step n3] statement [... statement ...] next var
The statements within the for command are executed with the variable = n1, then the 
variable is either increment by 1 or by the defined step (n3). The statements are 
repeatedly executed until the variable exceeds n2.

forever statement
Executes the statement forever, or until exited. Common ways of executing a forever 
are: goto, break or endfor.

gosub label
The program jumps to the subroutine named label. When a return command is executed then 
the program continues after the gosub command.
Note: If using the push or pop commands then remember to keep the stack 'balanced'.

goto label
The program jumps to the label.

if n [then] statement [else statement]
If n is true (not 0) then the first statement is executed, if false then the second 
statement is executed. The else (second) statement is optional.
Note: the word then is optional.

next var [,...]
The variable is incremented by 1 or step (n3) if specified; as defined by the related 
for command. If the variable is less than the end value (n2) then the for statement is 
executed again.

on break statement
The on break interupt is set so that when the break key is detected, the on-break 
statement executes.
After the on-break statement finishes then program execution returns to where the break 
key was pushed.

repeat n statement
The statement is executed n times.
return [n]
Returns from a function or gosub, optionally returning a value.
Note: If using the push or pop commands then remember to keep the stack 'balanced'.

stop
Stops the program and returns to DOS. All memory used by the program is automatically 
free and interupts 08h and 10h are reset if they were set by FAST.
stop is the same as: reset interupts:int 20h
stop is exactly the same as the terminate command.

stop resident
The program returns to DOS but remains in memory. All files that are open remain open 
and all memory allocated remains allocated.
All interupt vectors which have been altered also remain altered/active.
This command should be used by terminate and stay resident programs (TSR's).

terminate
terminate is exactly the same as the stop command.

test break
If the break key has been pressed then the current on-break statement is executed.

wait for n
n is computed until true (not 0).
Example: wait for key=' '       ;wait until space is pressed.

while n statement
The statement is repeated until n is false (0).
Example: while x<50 print x:x++

COMMUNICATIONS

disable serial
The communications interupts are reset to their original state before the program was 
started.
Note: All programs that enable serial communications must disable serial before 
returning to DOS.

enable serial [n]
Enables the COM1 serial port to send and recieve data.
You can specify the baud rate, stop bits, parity and word length.

After enabling serial communications your program will just continue to run as normal. 
Whenever a character is received a special handler will automatically put the byte into 
a buffer, this buffer is defined using the special variables:

  serial_size - size of buffer in bytes.
  serial_seg  - allocated segment of memory for buffer.
  serial_head - address for next byte in buffer. If the buffer fills up then 
                serial_head will wrap around to 0.

Example: serial_head=0
         serial_size=10000
         serial_seg=allocate serial_size/16+1
         enable serial 0a3h     ;see below for parameter details...

         serial_tail=0          ;last byte 'we' read.

         forever
             {
             while serial_head<>serial_tail       ;characters in buffer?
                 {
                 print chr serial_seg[serial_tail]b;             ;print byte
                 serial_tail++                                   ;next byte
                 if serial_tail>=serial_size then serial_tail=0  ;wrap around?
                 }
             if key=27 then disable serial:stop   ;abort if nothing in buffer?
             }

The configuration byte (n) is made up of 8 bits: bbbppsww

        ┌──────────────────────────────────────────────────┐
        │  bbb          pp          s         ww           │
        │  baud rate    parity      stops     word length  │
        ├──────────────────────────────────────────────────┤
        │  000 =  110   00 = none   0 = one   10 = 7 bits  │
        │  001 =  150   01 = odd    1 = two   11 = 8 bits  │
        │  010 =  300   10 = none                          │
        │  011 =  600   11 = even                          │
        │  100 = 1200                                      │
        │  101 = 2400                                      │
        │  110 = 4800                                      │
        │  111 = 9600                                      │
        └──────────────────────────────────────────────────┘

Example: 2400 baud, no parity, 1 stop bit and 8 bits = 101 00 0 11
         enable serial 10100011b   ;or 0a3h in hex.
ERROR HANDLING

error [n]
Call the current on-error statement.
If n is specified then the error variable is set to n, otherwise the last/current  
error number is used.

error msg filename [,n]
Loads the error message file, locates the current error number (or the specified error) 
and prints the error message. Printing is done using DOS (ie: print dos).
This process requires 16k free memory.
If there is not enough memory or the file does not exist or any error occurs or the 
error number does not exist then error-msg will print 'Error n [DOS=de]' where n=error 
and de=dos error number (ie: 2-file not found or 8-insufficient memory).

Example: on error
             {
             error msg "\dos.err"
             stop
             }

on error statement
Sets the on-error statement so that when an error occurs the statement is executed. See 
above example.
Note: The error variable contains the error number.

FILE

change dir pathname
Sets the current directory to a new path.
Includes automatic error checking.

change disk n
Changes the default drive to n. 0=A: 1=B: 2=C: ...
change-disk does not detect errors, test using the cdisk function.

close #n
Closes the open file (opened by open or create).
Includes automatic error checking.

create #n,filename [,reclen]
Creates a file, ready for reading and writing. If the file already exists then it will 
be deleted, the length will be set to 0.
The optional reclen sets the record length, the default is 1. The seek command will 
multiply reclen by the offset you want, thus giving an easy way to acess files with a 
fixed record length.
The file will be referenced using the handle #n, eg: seek #2,50
Includes automatic error checking.

delete filename
Deletes the file, wildcards can be used in the filename.
Includes automatic error checking.

dir filename,address [,n]
Creates a table of directory entries at the address specified.
Dir will default by searching for all normal and archive files. If n is specified it 
represents the file attributes to search for.
The first word at address contains the number of files found.
Each entry from address+2 is a 13 byte structure containing 'name.ext',0
Since each filename has the 0 as the end character then they can be used as filenames 
by all other FAST commands, eg: load segment:0002,buffer will load 'fast.com'.

Example: dir "*.*",segment|0

     segment:0000 = 3400  (peek segment|0 will give 34h = 52 files).
     segment:0002 = 'FAST.COM',0,?,?,?,?
     segment:000F = 'FASTL.HLP',0,?,?,?
     segment:001C = ...

find first filename [,n]
Finds the first occurrence of a filename - optional wildcards.
Includes automatic error checking.

n is an optional file attribute for finding files, the default is all normal files.
              ┌────────────────────────┐
              │ Bits      Attribute    │
              ├────────────────────────┤
              │ 76543210               │
              │ .......1  Read only    │
              │ ......1.  Hidden       │
              │ .....1..  System       │
              │ ....1...  Volume label │
              │ ...1....  Directory    │
              │ ..1.....  Archive      │
              └────────────────────────┘
If the attribute (n) is set to 0 (the default) then all read only, archive & normal 
files are found. If the directory, hidden or system bits are set then they are found 
aswell as normal files.

The information for the file found is at address:
    dta segment|dta offset + 15h  = File attribute (see table above).
                           + 16h  = Time stamp (2 bytes).
                           + 18h  = Date stamp (2 bytes).
                           + 1Ah  = File size in bytes (4 bytes).
                           + 1Eh  = File name,0 (asciiz string, 13 bytes).

find next
Find next should be used after find-first to find all subsequent files.
Includes automatic error checking. If there are no more files then error 18 will occur.

Example: #errors off
         find first "*.*"   ;Find the first file.
         goto entry
         forever
             {
             find next              ;Next file.
             #errors on
             entry:
             if error=18 then goto finished
             if error then error    ;Handle genuine errors with normal error handler.
             ;Process File.
             }
         finished:                  ;no more files...

fname string
fname is used to define filenames. fname is the same as the datab command except a 0 
byte is appended to the string automatically (ie: datab string,0).
Example: open #2,output_file
         ...
         output_file: fname 'file.lst'

handle #n1,n2
Overrides the file handle for any FAST files from #1 to #12.
n2 could be another FAST handle (eg: #1 thru #12) or a standard DOS handle, 0 to 4.

A handle is a number which represents a file that has been opened or created. All FASTs 
file comamnds & functions use #1 to #12 to represent a file.
In reality #1, #2 ... #12 are variables which contain the DOS handle number.
Example: open #1,myfile  ;sets #1 = next availble DOS handle number, typically 5.

DOS has 5 default handles which can also be used for input and output but they don't 
represent files. They are:

       ┌──────────────────────────────────────────────────────┐
       │ 0  Standard input device, input can be redirected.   │
       │ 1  Standard output device, output can be redirected. │
       │ 2  Standard error device, cannot be redirected.      │
       │ 3  Standard auxiliary device.                        │
       │ 4  Standard printer device.                          │
       └──────────────────────────────────────────────────────┘

For example to write bytes to the standard auxiliary device using FAST commands such as 
write #1,50 from address could be done, try...

            handle #1,3               ;sets fast handle #1 to DOS handle 3.
            write #1,50 from address  ;write bytes to auxillary device.

Note: The five standard DOS handles (0-4) don't have to be opened before use.

load filename,address [,length]
Loads the file into memory at address. Maximum load is 64K (65536 bytes), specify the 
length to restrict the number of bytes being loaded.
Includes automatic error checking.
The load command performs the same function as the following:
    open #spare,filename
    null=read #spare,length to address
    close #spare

make dir pathname
Makes the directory from the current directory. Same as DOS: mkdir pathname.
Includes automatic error checking.

open #n,filename [,reclen]
Opens a file, ready for reading and writing. 
The optional reclen sets the record length, the default is 1. The seek command will 
multiply reclen by the offset you want, thus giving an easy way to acess files with a 
fixed record length.
The file will be referenced using the handle #n, eg: seek #2,50
Includes automatic error checking.

reclen #n1,n2
Changes the record length of any open file to value n2.
The record length is used by the seek command.
remove dir pathname
Removes the directory from the current directory. Same as DOS: rmdir pathname.
Includes automatic error checking.

rename filename to filename
Renames the first filename to the second filename, wildcards can be used, same as DOS 
ren command.
Includes automatic error checking.

save filename,address,length
Creates the filename, writes the bytes from the specified address then closes the file.
The maximum length is 65535 bytes.
Includes automatic error checking.

seek #n,record
Moves the file pointer to the nth record. The file offset in bytes = n * reclen.
The default record length is 1, therefore record is simply the offset in bytes.
Record can be a 32 bit expression, therefore files upto 4 Gigabytes can be addressed.
Includes automatic error checking.

write #n,length from address
Writes the number of bytes to the open file.
The bytes are written to the current file offset. The current file offset is 0 when a 
file is opened, the seek command can be used to point to any offset within a file.
The write command will update the current file offset so the next write will append.
To read bytes from a file use the read function (see File Functions).
Includes automatic error checking.

GRAPHICS

hgraphics
Puts a hercules (or compatible) graphics card into graphics mode, screen resolution 
720*348. The mode command must also be used to tell FAST how many rows across and what 
sort of plot method is to be used: eg: mode 720,and.
For CGA, EGA and VGA cards use the screen command to change to graphics modes.

htext
Puts a hercules (or compatible) graphics card into text mode after using hgraphics.

line x1,y1 to x2,y2
Draws a line on a graphics screen in dots from x1,y1 to x2,y2.
The screen command should be used to set the graphics display, the mode command should 
be used to set the screen width and plot method.

mode n,m
Tells FAST graphics commands the width of the graphics screen and what plot mode should 
be used, either and, or or xor.
n can be either 320,640 or 720 (currently supported by FAST).
m can be and, or or xor.

plot x,y
Plots one dot (pixel) on the graphics screen. Colour should be set to determine what 
colour the dot will be.

shape "????????????????"
Defines a shape to be used by the SPRITE command. Sprites can be any width in multiples 
of 16 pixels.

When defining sprites for MODE 640 or MODE 720 then each character within the shape 
string represents one pixel, MODE 320 uses two characters - 4 colours.

The ???? should be replaced with * to represent a bit and spaces to represent spaces.

Example: datab 1,8   ;This sprite will be 1*16 pixels wide and 8 pixels high.
         shape "                "
         shape "  ************  "
         shape "  ***      ***  "
         shape "  **        **  "
         shape "   ***    ***   "
         shape "     ******     "
         shape "       **       "
         shape "                "

sprite x,y,address
Puts a sprite (bit image graphic) on the screen which must be a graphics screen.

A sprite is defined by the contents of the bytes at 'address'.
    address + 0 = width of sprite (in words) 1=16 bits/2=32 bits etc.
    address + 1 = height of sprite (in pixel rows).
    address + 2 = shape data (width*2*height bytes).

Example of a sprite 16 pixels across and 5 pixels high.

screen 6:mode 640,and
sprite x,y,sprite_address
stop

sprite_address:
datab 1,5
shape "       **       "
shape "   **********   "
shape "****************"
shape "   **********   "
shape "       **       "

MATH

div64 address,n32
Divides the 64 bit number stored at address by the 32 bit number, storing the 64 bit 
result back in address.
The 64 bit number is stored in low....high format.

mul64 n32,n32 address
Multiplies n32*n32 and stores the 64 bit result at address.
The 64 bit number is stored in low....high format.

Example: mul64 200000,500 addr
         result_low=peek addr        ;result_low must be a 32 bit variable.
         result_high=peek (addr+4)   ;Must be a 32 bit variable.

randomize n
Sets a starting point for the random number generator.
To get random numbers each time a program is run use the command: randomize timer.
Random numbers are obtained using the rnd function.

MEMORY

data n [,...]
Stores word values in memory.
Example: data 5000,10000,15000,20000

datab [n] [string] [,...]
Stores byte values of n or strings in memory.

Examples: datab 2,3,4,5
          datab 'name.txt',0
          datab 255,'test',0

deallocate n
The memory segment n is deallocated (freed). No more references to the memory segment 
are allowed, a severe memory allocation error could result.
Includes automatic error checking.
Memory is allocated using the allocate function.

fill[b] length from address with n
Fills the memory at address with n, length times.
fill is for word values (16 bits/2 bytes). fillb is for byte values.

free memory
Frees memory in excess of FAST's requirements, leaves the minimum amount of memory for 
code, variables, windows and stack space.
free memory is done automatically when a program starts so not used in normal 
situations.

free all memory
Frees all memory used by the FAST program, including the code segment.
free all memory is used by resident programs when they abort. Because free all memory 
uses DOS functions it can only be done when DOS is not being used. Check the tsr.f and 
pu.f programs for a guide to TSR programming.

modify segment to n
Modifies the length of an allocated memory segment.
n specifies the length in paragraphs. 1 paragraph is 16 bytes.
Includes automatic error checking.
A memory segment can almost always be reduced in size but enlarging a segment depends 
on the available memory and whether or not other segments have been allocated.

move[b] length from address to address
Moves the number of words (or bytes if moveb) from the first address to the second 
address. The maximum number of words moved at once is 32768, the maximum number of 
bytes is 65535. If the length=0 then nothing is done.
Note: Move will never over-ride memory, the move command determines automatically 
whether a forward or backward move is requried.

poke[b] address,n
The word (or byte if pokeb) is put into memory at address.
Words are stored in low,high byte order.
The peek function retrieves values from memory.

read[b] v [,...]
Reads a value from the current restore address and puts it into the specified variable. 
The restore address is incremented by 2 (1 if readb).

restore address
Sets the restore address, to be used by the next read command.

Note: The read command reads words/bytes from memory whereas the read function reads 
bytes from a file or device.

Example: proc draw_pic(pic_address)
             {
             restore pic_address                ;start of picture data.
             lx=-1

             loop:
             read x,y                           ;get x,y coordinates.
             if x=-1 then return
             if lx>0 then line lx,ly TO x,y
             lx=x:ly=y
             goto loop
             }

space n
Defines a work area of n bytes. n must be a constant value at compile time.
All bytes are set to 0 by default. 
space is identical to using datab 0 n times.

If defining space for a variable or buffer area then it is preferred that you define 
the work area using: label ? n   
n bytes will be reserved in memory, not part of the code.

Examples: table: space 200   ;puts 200 bytes of 0 into the FAST program.

          table ? 200        ;reserves 200 bytes in the variable area.
                             ;the 200 bytes will contain undefined values.

PROCEDURE

Procedures and Functions are exactly the same in FAST. The 3 words function, procedure 
and proc are allowed to define procedures (or functions, whatever you call them).

function name [ (var [,...] ) ] statement

A function is given a name, an optional number of parameters and a statement.

Example: function confirm (default)
             {
             print dos "Press Y to confirm [";
             if default then print dos "Y"; else print dos "N";
             print dos "] ";
             bad_key:
             wait for keypressed
             k=lcase key
             if k='y' then return 1
             if k='n' or k=27 then return 0
             if k=13 then return default
             goto bad_key
             }

The confirm function can be used in several different ways...

confirm                  ;used as a procedure (ie ignores the return value).
                         ;no parameter is specified therefore 'default' is undefined.
confirm(1)               ;used as a procedure, the return value will be lost.
x=confirm(0)             ;x=confirm 1 (yes) or 0 (no).
if confirm(1) then stop  ;if press Y or ENTER then stop.

Functions must be defined before they are used or a compiler error will result.
SCREEN

cls
Clears the current display page. 
To clear a text screen set the colour to the default colour, eg 7 or 15?
To clear a graphics screen set the colour to 0.

curpos=n
Sets the cursor position where n = y*256 + x.
The function to determine where the cursor is is also called curpos.

cursor y,x
Sets the cursor position used by the print dos command.

curtoloc
Sets the print location variable to the same screen position as the cursor.

locate y,x
Sets the locpos (print location variable) to row y, column x.
Locate is a nicer way of saying: locpos=y*160+x*2

loctocur
Sets the cursor position to the same as the current print location (locpos).

page n
Sets the current screen page, see the screen command for the number of pages in each 
display mode. A CGA or compatible graphics card as 4 pages of 80*25 colour text 
screens.
The first page is always 0.

print options
The print command is used to print text and numbers to the screen or printer.

Two other print commands exist: prints command - prints characters to the screen.
                                printm function - prints characters "intelligently".

The following print commands are available, they are also variations on print:

┌─────────────────────────────────────────────────────────────────────────────────────┐
│              Direct screen printing, options: cr tab chr , ;                        │
│ print        Numbers are printed in decimal form.                                   │
│ printb       Numbers are printed in 3 digit byte form: 000                          │
│ printh       Numbers are printed in hexadecimal: 0000                               │
│ printhb      Numbers are printed in hexadecimal: 00                                 │
├─────────────────────────────────────────────────────────────────────────────────────┤
│              Print using DOS function calls, options: cr lf tab chr ;               │
│ print dos    Printing using the DOS function calls.                                 │
│ print bios   Printing using the DOS function calls (provided for compatibility).    │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ sprint       Super fast printing using the sppos command, options: cr chr ;         │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ lprint       Printing to the printer, options: cr lf ff tab chr ;                   │
└─────────────────────────────────────────────────────────────────────────────────────┘

cr  = carriage return (print assumes cr includes lf).
lf  = line feed
ff  = form feed (new page).
tab = moves cursor to next column (8 character columns).
chr = print a character, eg: print chr 65 - prints 'A'.
;   = don't print on a new line, ie: suppress automatic cr and lf.
,   = moves cursor to next column (16 character columns).

Note: Comments (;) are not allowed after print because ; is a print option.

Examples: print "Hello"                  - "Hello", printing will start on next line.
          print "Hello";                 - "Hello", printing resumes after the "o".
          printh bios "Address = ";mem   - "Address = A23F"
          lprint count;" lines output."  - "50 lines output."
          print "line1" cr "line2" cr    - "line1" cr/lf "line2" cr/lf
          print x tab y , chr peekb m    - "10      12                      A"
          print chr peekb m;

screen n
Sets the screen display to any type, including support for HGA, MDA, CGA, EGA, VGA and 
any others which use the BIOS INT 10h for setting video modes.
mode should be used in conjunction with screen to set graphics modes.

 ┌───────────────────────────────────────────────────────────────────┐
 │  n    Type   Resolution   Adapter(s)     Colours    Video Segment │
 ├───────────────────────────────────────────────────────────────────┤
 │  0     T      40 x 25     All but MDA    16 gray         B800     │
 │  1     T      40 x 25     All but MDA  16 fore/8 back    B800     │
 │  2     T      80 x 25     All but MDA    16 gray         B800     │
 │  3     T      80 x 25     All but MDA  16 fore/8 back    B800     │
 │  4     G     320 x 200    All but MDA        4           B800     │
 │  5     G     320 x 200    All but MDA      4 gray        B800     │
 │  6     G     640 x 200    All but MDA        2           B800     │
 │  7     T      80 x 25     HGA,MDA,EGA       b/w          B000     │
 │  8     G     160 x 200       PCjr           16           B000     │
 │  9     G     320 x 200       PCjr           16           B000     │
 │ 10     G     640 x 200       PCjr            4           B000     │
 │ 11     R  (internal to EGA)                                       │
 │ 12     R  (internal to EGA)                                       │
 │ 13     G     320 x 200       EGA            16           A000     │
 │ 14     G     640 x 200       EGA            16           A000     │
 │ 15     G     640 x 350       EGA            b/w          A000     │
 │ 16     G     640 x 350       EGA            16           A000     │
 └───────────────────────────────────────────────────────────────────┘

scroll [down] x1,y1,x2,y2,n
Scrolls the area up (down if specified) n rows. If n=0 the area is cleared. The current 
colour will be the default for the blank line on the screen.
x1,y1 is the top left hand corner, x2,y2 is the bottom right.

Examples: scroll 0,0,24,79,1     ;scroll entire screen up 1 line.
          scroll 10,20,16,80,0   ;clear a window.

sppos
Sets the SI register for super fast screen printing using the command: sprint. The SI 
register can be manipulated by other FAST commands and so use sppos and sprint 
together.

Example: sppos
         m=start_file
         while peekb m sprint chr peekb m;:m++

There are 2 other fast print commands: prints and printm (printm is a function), 
neither command is related to sppos but both offer alternative fast printing.
SOUND

beep
Prints the BELL (character 7) to standard output, ie: print dos chr (7);

noise count,frequency
Produces a noise at the specified frequency. The count represents a time that the noise 
will last for, 20000 is approximately 1 second on a 4.77mhz PC.
The noise is not automatically turned off after it finishes, use the command noise off.
The frequency is calculated as: frequency = 1,331,000 / real frequency.
Example: 1,331,000 / 440 Hz = 3025, noise 20000,3025 = 440hz for 1 second.

noise off
Turns the speaker off.

sound duration,frequency
Turns the speaker on, producing a noise at the specified frequency.
Duration is the number of interupts (1/18.2 second intervals) the sound will last for 
before automatically being turned off. Duration is a FAST variable and can be set like 
a normal variable, eg: duration=1. After every clock interupt the duration variable 
will be decremented by 1, until 0.

STRING

asciiz n
Changes the end character of the string at address n to 0, so the string can be used as 
a filename by the FAST file commands.
The string must be defined using the string command, strings are input from the 
keyboard using the inputs command, the compiler directive #inpend can be used to 
automatically make the string end character 0 (the default is 13 - carriage return).

inputs n
Simple input from the keyboard at the current cursor position. n is a label or address 
referencing a string as defined by the string command.
A set of extended input commands are provided in the extinput.fi include file, the 
editing is much nicer but the programs add about 1K to the code.

string n
Defines an area in memory for a string.

A string is defined as follows: maximum length    ;same as n
                                current length    ;0 by default
                                string            ;0's by default
                                end_character     ;0 by default

If a string is input using the inputs command then the end character will be 13 by 
default (can be changed using the #inpend compiler directive).

Example: filename: string 40    ;memory at address filename = 40,0, 0*40, 0

SYSTEM

call address
The code at the specified address is executed.
If the address is segment|address then an inter-segment call is done (call far) and a 
far return must be done (retf).
If the address does not specify a segment then the current code segment is used, a near 
return must be used to return (ret).

clocks n
Sets the new timer tick frequency to 1,193,181 / n.
Changing the computers interupt frequency will effect the computers time (and possibly 
other, more important things).

Example: clocks 29830   ;1193181/40 = 29830
         on int 1
             {
             ;this code will be done 40 times a second.
             }
         ... program ... gets interupts every 40th of a second.

To reset clocks to 18.2 second intervals then use: clocks 0  (1193181/18.2 = 65536)

disable interupts
Disables all interupts, including timer, keyboard and other maskable interupts.
This command should probably only be used when using the out command and in function 
for controlling the computers hardware (same as ASM: cli).

dos n1 [(n2)]
Performs DOS function calls (int 21h).
* n1 & n2 are hexadecimal numbers, regardless of definition. *

Example: dos 4d (0)     ;same as ASM: mov ax,4d00h, int21h.

enable interupts
Enables all interupts (same as ASM: sti).

execute filename,n

halt
Halts the CPU using the assembler HALT instruction. This command can be used for timing 
and synchronisation. HALT halts the CPU until the next interupt.

inline n [,...]
Stores the byte values n in memory.
inline is exactly the same as the datab command, inline should be used when storing 
machine code instructions for ease of code reading.

int n
Calls the interupt handler. n ranges from 0 to 255.
To set or get an interupt vector address then use the getint and setint commands.
* n is a hexadecimal number, regardless of definition. *
A description of the IBM PC interupts can be found in most Technical Reference manuals 
or IBM PC Programmers Books.

Example: int 10         ;means INT 16 decimal.

iret
Interupt return, same as assembler: iret.

jump address
The program starts executing code at the address.

on critical

on debug statement
Any program lines that are compiled while debugging is on (#debug on) will execute the 
current on debug statement first.
If no on debug statement is defined the default statement tests for the break key.
Note: Debugging must be turned off while the compiler compiles the on debug command.

on int n statement
Sets one of FAST's 12 interupts to perform a statement. n ranges from 1 to 12.
Each interupt is run by the system clock interupt (18.2 times per second).
FAST's 12 interupts are timer only and not to be confused with the computers 256 
interupts or DOS's functions. FAST's interupts all join themselves to int 08h.
The stop int command will stop any of the 12 interupts from processing.

Note: DOS functions and any FAST commands which use DOS functions (file comamnds and 
some others) must not be used within the on int statement. There are some exceptions 
but special checks must be made before DOS functions can be done within interupts. See 
the example program tsr.f, this shows are interupts can be used for Terminate and Stay 
Resident programs.
on int can be used to give your program real time response and smooth action.
Eg: Running a game on different speed computers.

on idle statement
The idle interupt is intercepted by the on idle command (int 28h).
DOS calls the idle statement when waiting for keyboard input.
To call the idle statement from within your own programs while idle then use the 
command: int 28h
stop idle restores the interupt to its state before on idle was used.
on idle can be used to detect when DOS is not doing anything, see the example program 
tsr.f for an example.

on key n statement
When the specified key is pressed the statement is executed. n ranges from 32 to 127.
n is the ascii value for the keypressed, run the hexd utility to get the key code.
FAST will automatically use interupt vector 09 (keyboard interupt).

on scan n statement
When the specified key is pressed the statement is executed. n ranges from 0 to 132.
n is the scan code for the key, run the hexd utility to get the scan code.
FAST will automatically use interupt vector 09 (keyboard interupt).

on trace statement

out n1,n2
Same as the assembly command out, the value n2 is sent out the IO port n1.
The in function reads IO ports.

pop var [,...]
Pops the last pushed value from the stack and assigns the value to a variable.
All push-pop commands must relate to each other exactly, never push a value without 
poping it later. Never leave values on the stack within a subroutine (ie: push without 
pop).

popall
Pops all the computers registers from the stack, used in conjunction with pushall.

psp n
Sets the current Program Segment Prefix (PSP) to point to the segment n.
The default PSP segment for any FAST program is the same as the code segment because 
FAST uses .com files which have only one program/code segment.
Each program run under DOS has a PSP, the PSP segment contains a 128 byte block of 
information for DOS. For .com files the PSP segment = the Code Segment (CS). The PSP 
info is stored at address CS:0000 thru CS:007F
See example program tsr.f for using the psp command and psp function.

push n [,...]
Pushes the word value onto the stack. pop retrieves values off the stack in the 
opposite order, ie: Last In First Out.

pushall
Pushes all the computers registers onto the stack, to be retrived later using the 
popall command.

Registers pushed (in order): AX BX CX DX BP SI DI ES DS.
Registers not pushed: SS SP CS (stack and code segment)

reg rr=n [,...]
Sets any of the computers registers to n.
rr = AX BX CX DX SI DI BP SP DS ES CS.
n should be a constant or variable. If setting the AX register then set it last.

reset interupts
Resets the interupts 08 and 09 if they were automatically set by FAST. FAST will 
automatically use these interupts if your program uses the on int, on key or on scan 
commands.
FAST tells you if these interupts are used after compiling a program.
The stop and terminate commands automatically reset interupts, see the tsr.f (terminate 
and stay resident skeleton program) for using interupts.

retf
Return Far, same as the assembly instruction: retf

setint n to address
The interupt vector n is set to address.
There are 256 interupts vectors, 0 to 255, consult a technical reference manual for a 
description on each interupt.
* n1 & n2 are hexadecimal numbers, regardless of definition. *

shell string
Passes the string to DOS using the COMMAND.COM program.
Includes automatic error checking.

stack=n
Sets the stack pointer to address n (register SP = n).
The stack function = the current stack address.

stop critical

stop debug
Stops the current on debug statement from being executed for every line which was 
compiled while debugging was on (#debug on).
Do not confuse this command with the compiler directive #debug off.

stop idle
Stops the current on idle statement by restoring the old interupt vector to its 
previous state (DOS does nothing during the on idle interupt by default but some TSR 
programs may take control of it).

stop int n
Stops the FAST interupt from processing, n ranges from 1 to 12.

stop key n

stop scan n

stop trace
Stops the current on trace statement.

timer=n
Sets the low part of the system timer to n. This effects the computers current TIME.

VARIABLES

const label=n [,...]
Assigns a constant value to a label. The value is a word value, 0 to 65535.

const32 label=n [,...]
Assigns a constant value to a label. The value is a double word value, 0 to 4294967295.

let var=n
Assigns value n to the variable. The word let is optional.

swap var1,var2
Swaps variable values var1 and var2. 
The variables can be unsigned or signed 16 bits only.

unsigned var [,...]
Defines an unsigned variable: 16 bits, range 0 to 65,535.

var var [,...]
Defines a signed variable: 16 bits, range -32,768 to 32,767.

var32 [,...]
Defines an unsigned variable: 32 bits, range 0 to 4,294,967,295

WINDOW

close window
Closes the last opened window, if no window is open then an error will occur: 6 Invalid 
handle.
Includes automatic error checking.

close windows
Closes all open windows, does nothing if no windows are open.

open window n
Opens a window on the screen. Windows can only be used in 80 column colour text mode, 
this is the default for almost all applications so this should be a small limitation.
The close window command closes the most recently opened window.

If open window gets an error then this is handled by automatic error checking.
Error 4 occurs if no more windows can be opened - No more handles available (20 max).
Error 8 occurs if no more window memory - Insufficient Memory, increase the size using 
#window memory, the defaults size is 1500 bytes.

n is an address which points to a description of the window, defined as follows:

┌─────────────────────────────────────────────────────────────────────────────────────┐
│ mode            0=window with boundary only (used for creating standard windows).   │
│                 1=window with top line for window heading, used by select function. │
│                   Options can be selected in the window by pressing enter or the    │
│                   first letter of the option, eg: M for Menu.                       │
│                 2=Same as mode 1 but options must be selected by pressing Enter.    │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ options         Number of selectable options in the window/menu, used by mode 1 & 2.│
├─────────────────────────────────────────────────────────────────────────────────────┤
│ x1,y1           top left hand corner of window.                                     │
│ x2,y2           bottom right hand corner of window.                                 │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ colour          colour for the window (see the colour command).                     │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ [text [...] ]   All information here will be printed within the window.             │
│                 Use the following control codes:                                    │
│                   20,n    ;sets the colour to n for text.                           │
│                   22,x,y  ;sets the text location to x,y (relative to window).      │
│                 See example below.                                                  │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ eof             End of window definition (character 26 or 1A hex).                  │
└─────────────────────────────────────────────────────────────────────────────────────┘

Example: open window win_status      ;Open a typical status window.
         ...                         ;Print details inside window.
         wait for key=27             ;user must press escape.
         close window

         win_status:
         datab 0,0,40,14,79,24,15       ;mode, options, x1,y1, x2,y2, colour
         datab 22,1,4,'System Status'   ;text...
         datab 26                       ;eof.

Note: The print command does not use the current windows origin for printing, the whole 
screen is used as always.
COMMAND SUMMARY

FAST FUNCTIONS

COLOUR

colour
The current colour, as set by the colour command.
colour is a FAST system variable.

CONTROL

input[h][b]
Gets numeric input from the keyboard. If escape is pressed then the result is 0.

Examples: x=input       ;number, 0 to 65535.
          x=inputhb     ;number, 00 to FF (hexadecimal byte).
          x=inputb      ;number, 0 to 255.

key
The ascii value of the last key pressed (0 if no key pressed).
The key is removed from the keyboard buffer.

keypressed
Returns 1 if there are any keystrokes waiting in the buffer, 0 if none.

keyscan
Returns a word value (16 bits), the high byte is the scan code, the low byte is the key 
code. The key is removed from the keyboard buffer.

Example: ks=keyscan
         kk=low ks      ;key code
         ss=high ks     ;scan code

scan
The scan code of the last key pressed (0 if no key pressed).
The key is removed from the keyboard buffer.

COMMUNICATIONS

serial_status
Returns the status of serial port 1 for the line and modem.

line_status  = high serial_status   (high byte)
modem_status = low  serial_status   (low byte)

 AH (Line status)
 ----------------
   Bit  7 6 5 4 3 2 1 0
        1 . . . . . . .       Time-out error
        . 1 . . . . . .       Transfer shift register empty
        . . 1 . . . . .       Transfer holding register empty
        . . . 1 . . . .       Break-detect error
        . . . . 1 . . .       Framing error
        . . . . . 1 . .       Parity error
        . . . . . . 1 .       Overrun error
        . . . . . . . 1       Data ready

 AL (Modem status)
 -----------------
   Bit  7 6 5 4 3 2 1 0
        1 . . . . . . .       Received line signal detect
        . 1 . . . . . .       Ring indicator
        . . 1 . . . . .       Data set ready
        . . . 1 . . . .       Clear to send
        . . . . 1 . . .       Change in receive line signal detected
        . . . . . 1 . .       Trailing edge ring detector
        . . . . . . 1 .       Change in data set ready
        . . . . . . . 1       Change in clear to send

Example: ss=serial_status
         line_status=high ss
         modem_status=low ss
         if modem_status and 16 then print "Clear to Send"      ;16=2^4

serial_send n
Sends a byte to the serial port, COM1. serial_send uses the BIOS int 14h services to 
send characters.

To receive characters, use enable serial.

Example: See enable serial for a coms program using FAST.
         The phone.f program is a complete terminal emulator with file transfers. 
         Only available to registered users.

serial_seg

serial_size

serial_head

ERROR HANDLING

error
The current error number.
error is a FAST system variable.

errorv
The address of the current error handler.
errorv is a FAST system variable.

FILE

cdisk
The current disk drive. 0=A: 1=B: 2=C: etc

dta [offset] [segment]
The current disk transfer address offset or segment value.
This address is used by the find first and find next commands to store file 
information, unfortunately it is also the same address as the DOS command line area, 
ie: CS:0080 to CS:00FF. If you wish to store check for command line parameters then you 
should check them before using the find first or find next commands, or move the 
command line memory somewhere else: eg: moveb 128 from 80h to work_area

Example: dta_off=dta offset
         dta_seg=dta segment

handle #n
The actual DOS handle number of FAST's file #1-#12.
See the handle command for more information.

read #n,length to address
Returns the number of bytes read. Reads length number of bytes from the open file into 
memory at the specified address.
The file seek pointer is updated automatically, therefore the next read command will 
read bytes following the ones just read.
Includes automatic error checking.

Example: rn=read #1,10 to work_area     ;read 10 bytes from file #1.
         if rn<>10 then error 13        ;error if 10 bytes not read.
GRAPHICS

hit x,y

point x,y
Returns the colour value of the pixel at coordinate x,y (graphics modes only).
For black and white graphics modes the colour value is 1 for dots and 0 for spaces.
See the plot command.

MATH

abs n
Returns the absolute value of n, assuming n is a signed number (two's complement).

Example: print 2        ;prints 2
         print -2       ;prints 2
         print 65534    ;prints 2    (65536-65534)

high n
The high part of n, if n is a word value (16 bits) then the high 8 bits are returned as 
a byte value (0 to 255). If n is a 32 bit variable then the high 16 bits are returned 
as a word value (0 to 65535).

Example: print high 16384       ;prints 64. (16384/256 = 64)

low n
The low part of n, if n is a word value (16 bits) then the low 8 bits are returned as a 
byte value (0 to 255). If n is a 32 bit variable then the low 16 bits are returned as a 
word value (0 to 65535).

Example: print low 16384        ;prints 0. (remainder of 16384/256 = 0)

mod

not n
Returns 0 if n<>0 and 1 if n=0.

rleft[z] n
Returns the value of n, rotated left by 1 bit.
rleft will move bit 16 into bit 1.
rleftz will move 0 into bit 1 (rotate left with zero).

rnd
Random number (word value). The number is generated using a random seed set by the 
randomize command.

rright[z] n
Returns the value of n, rotated right by 1 bit.
rright will move bit 1 into bit 16.
rrightz will move 0 into bit 16 (rotate right with zero).

MEMORY

allocate n
Allocates n paragraphs of memory and returns the segment number.
A paragraph of memory is 16 bytes.
A block of memory allocated using the allocate function can be useful for loading 
files, work areas, storing data or anything.
Includes automatic error checking, ie: Not enough memory. If a program allocates a 
memory segment then overwrites the segment boundaries then a severe error will occur.

Example: text_seg=allocate 4096         ;4096*16 = 65536 bytes (64K).
         load "file",text_seg|0         ;load file into text_seg|0 memory

compare[b] n at address1 with address2
Compares n words (or bytes if compareb) at address1 with address2. If both memory areas 
are the same then the result is 0, otherwise the first mismatched address is returned.

Note: If address1=0 and 0 is returned this could mean that the areas matched or that 
the first byte was mismatched.

Example: diff=compare 2000 from video|2 with old_video|2
         if diff then update_new_screen

peek[b] address
Returns the word (byte if peekb) value stored at the address. Word values are always 
stored in low byte,high byte order.
If peek is used in a 32 bit expression (ie: var32=peek x) then a 32 bit value is 
returned.

search[b] length from address for n
Returns the address of the first word (byte if searchb) which equals n, if n is not 
found then 0 is returned.

Note: If the first word in the string is at address 0 and it equals n then 0 will be 
returned (ie: same value as if word was not found).

Example: found = searchb table_len from table for key
         if found then process_table(found)

SCREEN

curpos
Returns the current cursor postion as a word value, the x (column) position is the low 
byte value and the y (row) position is the high byte value.
Example: pos=curpos     ;pos=y*256+x

page
The current display page, the first page = 0.

printm address,n [,0]
Prints the characters on the screen stored at address and returns the address for the 
start of the next characters or line.

This function is ULTRA FAST for printing lines of text or file names etc on the screen 
at the current print (locpos) position using the current colour.
The colour can be left unchanged on the screen by appending the option ,0.

n is the width of the column of text to be printed, printm handles tabs and also fills 
the rest of the line with spaces if necessary.
The end character is either 0, 13 or 26 (null, cr or eof).

If a carriage return is encountered and the next character is a line feed then it is 
automatically skipped, returning the offset for the byte after the line feed.
If an end of file marker is found then the offset returned will remain at the address 
of the end of file character, hence it never goes over the edge.

Example to print an entire screen of text.

for y=0 to 24
locate y,0
mem=printm edit_seg|mem,80      ;print 80 character wide block, from edit_seg|mem
next y

Note: null            =  0
      carriage return = 13
      line feed       = 10
      end of file     = 26

scrchr y,x
The ascii value of the character at screen location y,x (row,column).

screen
The current screen mode, set by the screen command.

locpos

mono

video

SOUND

duration

STRING

digits n
Returns the number of digits in the printed form of the number n.

Examples: print digits 1        ;prints 1
          print digits 295      ;prints 3
          print digits 40000    ;prints 5

getint n
Returns the segment|offset address of the interupt vector n as a 32 bit value. The 
segment is the high word and the offset is the low word value.

Example: int9=getint 9          ;int9 must be a 32 bit variable.
         int9_offset=low int9
         int9_segment=high int9

lcase n
Returns the lowercase value of the ascii character n.

ucase n
Returns the uppercase value of the ascii character n.

SYSTEM

carry
1 if the carry flag is set, 0 if not.

in m
Returns the byte value from IO port n.
This is the same as the assembler in function.

psp
Returns the current PSP segment (Program Segment Prefix).
The default PSP for any running program is the same as the code segment.
The PSP command and function should be used within TSR programs (see the tsr.f skeleton 
program).

reg register
Returns the value of any register, either: AX BX CX DX DI SI BP SP ES DS CS.

stack
Returns the current stack address (register SP).

timer
Returns the value of the current time, in 18.2 second units.
The timer value can range from 0 to 1572480 so the timer function should be used with a 
32 bit variable, eg: var32=timer

Example: if timer = 240000 then the time = 240000 / 18.2 seconds from midnight.
         240000/18.2 = 13187 / 60 = 220 minutes. 220/60 = 3.66 hours.
         Therefore 240000, time = 3:40am

usr address
Calls the subroutine at the address (same as call command) and returns the value in the 
AX register. usr could be used to call an assembly routine which returns a value.

ihere

WINDOW

menu n [,default]
Opens the window n (see open window command), the selection bar appears.
The value returned will be the option number, starting from 1. If the user presses 
escape the value = 0.
default is the default option to start the selection bar on, if no default is given 
then the selection bar starts on option 1.
The window is not closed, use close window.

select n [,default]
Same as the menu function except the window must be already open.
The window is not closed, use close window.

FUNCTION SUMMARY

FAST EXPRESSIONS

Maths expressions: + - * /

Comparisons: =  <  >  <>  <=  >=  above  below

Variable assignments: =  ++  --  +=  -=  *=  /=

Expressions: ( ... )

Operators: and  or  xor

COMPILER DIRECTIVES

#debug on/off
All commands compiled while debug is on will call the current on debug statement.
The default on debug statement simply tests for the break key.
Each line compiled while debug is on will use 5 extra bytes.

#else
Used in between #if and #endif. See #if for an example.

#endcode
The compile stops compiling - artificial end of program marker.

#endif
Ends the current #if compilation. See #if for an example.

#entry
Sets the entry point for the FAST program, the default entry point is the first line.

#errors on/off
Any FAST commands which include automatic error checking will set the error variable to 
the error number (0 if no error).
While errors on, all commands which check errors will also call the error handling 
routine if an error occurs.
By default, #errors is on.

Example: (a) without errors on: #errors off
             open #1,"pu.cfg"
             if error then error    ;if there was an error run the error handler.

         (b) with errors on: #errors on (also the defalut)
             open #1,"pu.cfg"

#if n
If n is true (not 0) then the following command(s) are compiled until a #else or #endif 
are encountered.

Example: #if ledger
           #include ledger.fi
           #if charts
             #include charts.fi
           #endif
         #else
           #include trans.fi
         #endif

Note: n must be a constant value.
Note: #if can be nested to 20 levels.

#include filename.ext
The compiler includes the specified file into the source file and compiles it.
The full filename must be specified, including the extension. Drive and Pathname are 
optional.

Note: Every include file uses 10k of memory while being compiled.
#inpend=n
Changes the default end character for the inputs command, the default is 13.
If inputs is used only to enter filenames then set #inpend=0, therefore all inputted 
strings will automatically have the correct end of filename marker: 0.
There can only be one #inpend value in any program, if more than one is defined then 
the last one is used.

#local
All variables used or declared within procedures and functions will be local to that 
procedure or function.

Example: #local
         proc do_one (x,y,z)
             {
             x=10:y=20:z=30
             }

         proc do_two (x,y,z)
             {
             x=11:y=21:z=31
             }

Both procedures have their own variables x,y & z.
In the symbol table these variables will appear as x$do_one, y$do_one, x$do_one and 
x$do_two, y$do_two, z$do_two.

#long
The compiler will compile all if-then-else commands using long jumps rather than short 
jumps. See #short

#para
Aligns the next address the compiler uses to store commands or data with the next  
paragraph boundary. A paragraph boundary is a multiple of 16 bytes.
This directive should only be used when data must be stored on a paragraph boundary.

#protect
The compiler will include special self checking code to detect if the .COM file has 
been tampered with (ie: by a virus). If a change is detected then a message will appear 
and the program is aborted.

#setdos v.xx
Sets the DOS version needed to run the FAST program.
Any version set below the current #setdos version will be ignored, eg: #setdos 1.00 
will be ignored because the default minimum is 2.00
#short
The compiler will compile all if-then-else commands using short jumps rather than long 
jumps. The advantages of using short jumps are speed and size.
FAST can sometimes use only 1 instruction with #short instead of two instructions with 
#long.
Typically set #short at the start of every program (including include files). If a 
short jump cannot be used then the compiler will give an error. Simply put a #long at 
the start of the offending if command and a #short just after the if command.

Example: #long
         if k='s' then
             {
             #short
             ;more than 128 bytes of commands...
             }

#stack memory n
Sets the stack memory size to n bytes. The default size is 1024 bytes.

#trace on/off
All commands compiled while trace is on will be made traceable. FAST will save a 
special file containing the trace data: program.ft (program=compiled program name).
A special program called FASTT must be used to run the program when tracing it.
Trace means to single step through a program while it is running.

Example: 1. Insert #trace on/off commands around the blocks of code you want to trace.
         2. Compile the program.
         3. Run "FASTT program".

Note: Each line compiled with trace on will use 1 extra byte.

#window memory n
Sets the window memory size to n bytes. The default size is 1500 bytes.
If the window commands are not used then FAST will automatically set the window memory 
size to 0 bytes.


Compiler Directive Defaults

The following is a list of how FAST is setup before compiling starts:

    #debug OFF
    #entry
    #errors on
    #inpend=13
    #setdos 2.00
    #stack memory 1024  ;set by FAST Maintenance
    #trace off
    #window memory 1500 ;set by FAST Maintenance

The following list is how FAST is setup before compiling each file:
(note options are restored to their original setting after including a file)

    #long
DIRECTIVE SUMMARY

#debug on/off
#else
#endcode
#endif
#entry
#errors on/off
#if n
#include filename.ext
#inpend=n
#local
#long
#para
#protect
#setdos v.xx
#short
#stack memory n
#trace on/off
#window memory n
INCLUDE FILES

cmd_line.fi

colour.fi

extinput.fi

fast32.fi

fhelp.fi

fsort.fi

keys.fi

ERROR MESSAGES

  0 Unknown Error (contact PCS)

  1 Syntax error

  2 Number out of range

  3 Word undefined

  4 Double definition of word

  5 Expected a string expression using "string" or 'string'

  6 Invalid parameter(s)

  7 Internal stack error - recovered ok

  8 Excess characters in line - ignored

  9 Out of table space - increase with -m option

 10 Missing comma

 11 Missing end of string - " or '

 12 Warning... deallocation of memory failed after include

 13 Out of memory, exceeded the 64K limit

 14 #ENDIF without #IF

 15 Divide by zero not allowed

 16 Severe error in UNDEF TABLE

 17 Out of memory for UNDEFINED words - increase with -m option

 18 Warning! Undefined label (0 used)

 19 Word defined in way which contradicts its use

 20 Too many compiler #IF statements, maximum is 20

 21 Severe error in LABEL TABLE

 22 Unknown compiler directive

 23 Bad digit (unrecognisable number)

 24 Missing #ENDIF

 25 No room to include file

 26 Too many labels - increase with -m option

 27 *not used*

 28 Missing ),] or }

 29 Data types mismatch, conflict between two words or double declaration

 30 Missing equals '='

 31 Incorrect syntax, wrong seperator

 32 Missing numeric expression

 33 Cannot use reserved word as variable or label

 34 Compiler error, optimisation data tables corrupt

 35 Expected either ON or OFF

 36 Illegal character



100 Limit of 50 nested commands exceeded

101 Cannot set CS register directly, use CALL SEGMENT|OFFSET

102 Expected a valid file indicator - #n, n=1 to 12

103 Wrong number of parameters for function or procedure

104 Wrong type, expected a variable

105 Absolute address expected - Eg SEG|OFF or OFF

106 Wrong type, expected a label

107 Too many ERROR jumps (compiler error)!

108 Statement too long, reduce expressions to variables

109 Too many files compiled, max=50

110 Too many lines compiled, max=10389

111 Code exceeds short jump range

112 Invalid #SETDOS format: n.xx

113 End of file: REPEAT statement(s) not closed

114 End of file: WHILE statement(s) not closed

115 End of file: IF-THEN-ELSE statement(s) not closed

116 End of file: WAIT FOR statement(s) not closed

117 End of file: ON GOTO/GOSUB statement(s) not closed

118 End of file: PROCEDURE or FUNCTION declaration(s) not finished

119 End of file: FOREVER statement(s) not closed or ENDFOR mismatch

120 End of file: NEXT is missing from FOR loop

121 End of file: Unknown Reason, check {}

122 Nested procedure or function declaration not allowed


EXAMPLE PROGRAM DOCUMENTATION

clist
Print text files in two columns, using 17 characters per inch and 1/8" line spacing. 
The default settings are for epson compatible printers. Change the settings in the 
source file and recompile to suit your needs.

CLIST can be used for making hard copies of files when paper is in short supply or just 
to get more code on a page for easier debugging.

cmp
Compare two files by displaying any differences between the two files at all locations.
Each differnce is displayed as 'ADDR : B1 ! B2'.

All values are in hex. The address starts at 0. A file in excess of 64k is ignored.
ESC aborts while running. SPACE can be used to suspend the listing.

colour

compf
Compresses and uncompresses both FAST and ASM files.

Run COMPF: When asked for a file enter

    1) *.F to compress all FAST source files.
    2) *.ASM to compress all ASM source files.

    3) *.FX to uncompress all FAST source files.
    4) *.AX to uncompress all ASM source files.

Note: The file created (with the compressed data) is called _.FX or _.AX.

To compress a single file use its filename, eg WT.F; this will create a file
called WT.FX. Therefore to uncompress it use WT.FX as the file name.

Compf is a crude compression program, something like pkzip would be more suitable. 
However there can be added benefits to using compf and pkzip together. ie: compf all 
source files then pkzip the _.fx file.

cr
Counts the number of lines in any group of files (by counting carriage returns).

After entering CR you will be asked for the file(s), for multiple files use wild card 
characters, eg '*' & '?'.

d
Another directory command, 3 columns are displayed, sorted by name.
Directories are listed first, followed by files.

Examples: d           ;all files and directories.
          d \asm\     ;all files in the sub-directory \asm.
          d a:*.doc   ;all DOC files on drive A.
          d f         ;all files starting with F.

Press any key to suspend the directory - it scrolls fairly fast, escape to abort.
dl
A simple debugger which knows a little about FAST's memory areas and subroutines.
DL shows labels and the opcodes for any .COM file.

Syntax: DL program  (leave out the .COM)

The program DA is the same as DL except the it just creates a .ASM output file for 
assembling with SOFA - the .ASM file will need changes - upgrades will mean that DL/DA 
does everything, producing a ASM file 100% ok.

DA could be used once a FAST program has been completely written and debugged
for further optimising the program to run faster - using assembly language.

da
See dl.

demo
A demonstration of FAST.

dscr
Changes the print-screen button to save the screen image to a disk file.
When print-screen is pressed a popup box will appear asking for the filename.

edit
A DOS command line editor, allowing access to the last 16 commands entered.
The keys act the same as the normal DOS command line editor, when you press up or down 
then a popup menu appears with the last 16 selections: select one then press enter. The 
option can then be modified in the usual manner or executed by pressing enter.

ALT-X quits edit and frees up memory used (if no other TSRs loaded since EDIT). 
ALT-C clears the screen and resets the computer back to text mode.
CTRL-END clears to end of line from the cursor.

fastt
FAST TRACE utility to trace source files line by line.
See the compiler directive #trace for more instructions on tracing through a program.

Type 'FASTT program'. All the source files that were used to compile the program must 
exist in the current directory.

When tracing a program the full screen is used, pressing any key advances to the next 
line. If the scroll-lock light is on the FASTT will resume running the program as 
normal - until you take the scroll-lock light off.

Notes: FASTT uses 1 file handle for each source file that is actually traced, increase 
       the DOS file handles in the config.sys file if an error occurs.
       FASTT only works properly in the 80 column colour text mode.

ffind
Search for a string within specified files.
Type ffind with no parameters to see the current command line options.

Ffind displays the file it is looking through and when a match is found it
lists it on the screen.
free
Displays the number of Kilobytes free for DOS at anytime.

game
A small shoot-em up (try it - see what happens).

Playing keys: A     - UP
              Z     - DOWN
              ENTER - FIRE
              ESC   - EXIT

Must have a CGA card (or CGA emulator if HGA). EGA and VGA are good too but GAME only 
uses the CGA graphics mode: 640 * 200 black and white.

If the game is too fast then change it so that there are more background dots or put 
delays into the source file, then recompile it.
ie: Line 4, change const backdots=9 to another value, eg: 50.

hexd
TSR program that has 4 basic utilities, it may be more suitable than other TSRs because 
it uses very little memory (10k approx).

  1) Ascii table with all 256 characters shown at once. To find the number of a 
     character move the cursor using the numeric keypad (diagonal also).
     The character number is shown in hex and decimal at the bottom.

  2) Number conversion allows entry of a hex or decimal number which is then displayed 
     in DECIMAL, HEX and BINARY across the window. Press H to enter a hex number or D 
     to enter decimal. Press PgUp or PgDn to change the numbers.

  3) Keyboard codes - Press the key to see its KEY code, SCAN code and shift byte 
     values. KEY is the ascii value of the key. SCAN is the keyboard return code for 
     the key - includes arrows and function keys. KEYSCAN = SCAN * 256 + KEY
     Pushing ESC returns to the main menu - escape KEY = 27, SCAN = 1.

  4) Colours - shows the colour and its hex value.
     To read the colours HEX value - take the first hex digit from the righthand side
     down, the second digit from the row across the top.

Activate by using both left and right shift keys together.
To disable HEXD from working press D on the main menu.

To select an option from the menu either move bar with up/down or press the first 
letter of the option to activate immediately.

merr
Creates and maintains .err files (such as the dos.err file).
Start merr by entering the error messages full pathname: eg: \dos.err

Select a message using the arrow keys, modify by pressing enter.
A=Add, D=Delete, P=Print All, ESCAPE=save? and exit.
mis
A 1 or 2 player game. Each player (or computer) must try to destroy the enemy base by 
firing a missile at the opponent.
The game is played where both players move simultaneously.

Keys:       Function.        Player ONE   Player TWO
            ----------------------------------------------------
            Decrease angle       F1           7 (numeric keypad)
            Increase angle       F2           9 (numeric keypad)
            Decrease force       F3           1 (numeric keypad)
            Increase force       F4           3 (numeric keypad)
            Fire                tilde         2 (numeric keypad)

            Quit = ESC

Notes: A missile will blow up if it hits ANYTHING.
       The clouds give an indication as to the winds speed and direction.
       Each player scores 500 points for destroying the enemy base.
       A base will blow up if a) it has been hit sufficiently by missiles,
                              b) falling shrapnel has destroyed it.

Volcanoes can erupt from time to time; missiles will explode if they hit volcanic 
material; bases will explode if too much volcanic material lands on them; to stop a 
volcanoe blow it up.

music
A simple music program. Music was designed for entering the musical notes. The print 
feature in MUSIC converts the notes to tablature but is not 100% accurate as my 
knowledge of music is not great. I think I've got it working only when a song is in the 
key of D.

ALT-D Deletes the current Bar.
ALT-C Copies the current Bar.
ALT-R Toggles the 'repeat' status.
ALT-I Sets the current bar as containing the intro details, not repeated.
      Should only use this for the first bar, each sharpened note in the intro
      bar will represent the key of the music, ie: each sharpened note in the
      intro will be sharpened in the rest of the music.
      Don't put any note in the very first spot (each bar is 16 places).

S     Sharpen current note (brighter colour)
ESC   Save and Exit.
P     Play the music.
+/-   Increase/Decrease Tempo.
     Move note up/down tablature, ie: change note at cursor.
Del   Reset note, ie: no note.
a-g   Set note, change octave of current note.
ALT-G Prints guitar tablature to printer.

othello
The board game (also called Reversi). You can play either computer or human.

The computer uses a strange method for its moves, don't let it go to your head if you 
beat it a few times.
panprt
Special printing program, it reads in a file which can contain special control codes 
for nice printing. Read the PANPRT.F source file to view the control codes supported, 
add your own codes to the program.

pc
Displays all selected files on the screen sorted by filename.ext.

The user then selects a file by positioning the cursor over the filename and pressing 
ENTER (or P for printout).

A file called PC.FIL must be in the root directory of the current drive, if it doesn't 
exist then the default *.DOC is used. If PC.FIL does exist then it must contain 
filenames using wildcard characters (only files in the current directory can be 
displayed). PC.FIL can be created using any ASCII text editor.

Example PC.FIL: *.F
                *.LST
                *.DOC    (three seperate lines in the file.)

When a file is displayed any of HOME, END, UP, DOWN, PGDN & PGUP can be used to move 
around the file. If the line length is greater than 160 characters then the UP/PGUP 
will sometimes 'jump' the display.

PC will handle a maximum of 1024 files.
A wordstar option is provided, press W to toggle when in display mode.

pcsoft
Peter Campbell Software's One Fingered Typist utility program.
This program is supplied to registered users only.

Add "PCSOFT" to your autoexec.bat file to make PCSOFT active all the time.
With PCSOFT you push the shift key (shift, alt or control) and then push the other key. 
More than one shift key can be pushed, for example CTRL then ALT followed by DEL would 
do a system reset.

PCSOFT does not effect the current keyboard use in most cases, a multi-finger
typist would not notice it.

This program was designed for use by people with an interest or need for computers but 
are restricted to pushing one key with whatever possible means.
Secondary use: One hand using a mouse then second hand can still do everything.

phone
Terminal emulator and file transfer program to use calling BBS's or other data 
services. This program is supplied to registered users only.

Help is provided seperately with this program: phone.doc
The configuration file: phone.cfg.

pscr
Overrides the normal Shift-PrtSc function: 3 new features for Shift-PrtSc.

1) Allows selection of any part of the screen when in 80 column colour text mode (the
   default for almost every application).
         Keys: Move top-left corner with shifted-arrows.
               Move bottom-right corner with arrows.
               Press ENTER to print highlighted area.
               ESC to abort screen dump.

2) If using 320*200 colour screen then it will be printed with a little shading.
   Your printer must have the 640 dots per page graphics setting.
   All colours will be shaded using a 2*2 grid for the 4 colours.

3) If using the 640*200 graphics screen then it will be printed.
   Your printer must have the 640 dots per page graphics setting.

Note: If the screen is in any other graphics/text mode the default PrtSc is used.

pu
Printer Utilities is a comprehensive TSR program to set the printer options from the 
keyboard. TSR=Terminate and Stay Resident.

PU has 21 built in and 21 user definable printer options.

PU has basic features from the main menu, Line Feed, Form Feed, Reset and printing test 
messages to help setting up the printer.

The menu works with one-touch operation - press the first letter of the option to 
activate it.

Note: When Keeping the options (save) a copy of PU.CFG will be saved in the CURRENT 
      disk/directory.

purge
PURGE is a file deleter and one-page file viewer.

Type 'PURGE *.BAK' and all backup files will be displayed for selection.

Pressing F1 would select all files. Pressing D and confirming would delete all SELECTED 
files.

Pressing V displays the current highlighted file on screen, only the first page is 
displayed - just to jog your memory of what the file is.

Typing 'PURGE' assumes *.* (all files in current directory).

rkey
Key redefinition program. You can define any key to mean a whole series of keystrokes.
Rkey works by learning as you type.

Rkey's main use has been while editing source files to quickly use the learn and 
playback option to do repetitive tasks.
sed
Sector Editor allows access to all sectors on a hard disk, ignoring the partition 
limits.

SED can view a maximum of 1-64 sectors, 0-15 heads & 0-1023 tracks.

All menu options have their letter inverted on the screen.
Options:                              Range:
    1   - Alter max tracks            0 - 1023
    2   - Alter max heads             0 - 15
    3   - Alter max sectors           0 - 63
    T   - Set current track           0 - max tracks-1
    H   - Set current head            0 - max heads-1
    S   - Set current sector          1 - max sectors
    ESC - Abort SED
    A   - Change to ASCII display
    X   - Change to HEX display
    F   - Find a string from current sector to end of disk
    O   - Open disk output file
    W   - Write displayed sector to disk file
    C   - Close disk output file

Other keys:
    Arrows - move cursor (current version has no use)
    PgUp   - Back one sector
    PgDn   - Advance one sector

When using the ascii display there are two sides, the left displays the actual bytes - 
using the IBM character set. The righthand side shows the bytes in filtered form (bit 7 
is ignored, if less than 32 then prints a dot '.'). To print the screen using the PrtSc 
button then load PSCR prior to printing so the right hand side of the screen (when in 
ASCII display mode) can be printed, printing the actual IBM characters will cause the 
printer to process them as control codes.

If the program gets a disk error then you will have the options
to either S - Try next sector or H - Try next head.

shoot
A one or two fast shoot-em up game.
The object is to kill your oponent by shooting their space ship.

Each player is limited to 50 shots, when both players run out of ammo each player is 
re-stocked with another 50 shots and so on.

Scoring: For shooting your oponent you get 200 points.
         For shooting a person or car then you get 2 or 5 points.
         For shooting trees, walls and rocks no points are scored.

The game ends when a player has killed his/her oponent 10 times.

Player 1 uses  F2, F4 & tilde                    (up, down and fire)
Player 2 uses  4,  1  & + on the numeric keypad  (up, down and fire)

SHOOT C = one player vs computer.
SHOOT   = two players.
sieve
Standard benchmark. This version in FAST compares favourably with all other versions 
I've seen, especially in size and speed (what else!).

tsr
Terminate and Stay Resident skeleton program for use in writing TSR programs.

The smallest TSR program is just over 700 bytes long, this is the smallest overhead set 
by any language I know of (except Assembly).

wt
Text editor designed mainly for programming.

WT summary of features:

a) WT can have a different configuration in each sub-directory so you have a
   different tab value, default file extension and backup settings.
b) Up to 16 files can be edited at once.
c) Search/Replace is instant/quick.
d) Full line and column blocks can be easily defined. The most recently defined block
   is saved as the \WT.INS file, push Shift-Insert to insert the current block.
e) Most people like 1 editor and stick with it, no one ever makes a compromise when it
   comes to their editor. WT can be modified by you for personal customisation.
f) WT can keep a log file with the file, date & time for each file which is edited.
